home *** CD-ROM | disk | FTP | other *** search
/ Fritz: All Fritz / All Fritz.zip / All Fritz / FILES / PROGNG_C / DBTOOLC.LZH / README1 < prev    next >
Text File  |  1987-10-30  |  22KB  |  676 lines
  1. dBASE TOOLS FOR C: The Programmer's Library, Version 1.4
  2.  
  3.                          INCENTIVE DISK
  4.  
  5. This README contains update information about The Programmer's
  6. Library Incentive Disk. Note that the files on this disk are 
  7. supplemental and assume that you still have the previous version 
  8. available. Check for additional "readme" files in the
  9. various subdirectories on the distribution disk. The major points
  10. are summarized here:
  11.  
  12.   1. Summary of Additional Functions
  13.  
  14.   2. Documentation Errors
  15.  
  16.   3. New Error Messages
  17.  
  18.   4. Compiler Variations
  19.  
  20.   5. Notes on Recompiling The Programmer's Library
  21.  
  22.   6. Pre-Parsing of CFUNC Parameters
  23.  
  24.   7. Documentation Pages for New Functions
  25.  
  26. 1. Summary of Additional Functions
  27.  
  28.     The following functions have been added:
  29.  
  30.     ARAND       Fill an array with random #'s
  31.     ASAVE       Save the contents of an array to disk
  32.     ARESTORE    Restore an array from a disk file
  33.     CHI         A chi-square statistic function
  34.     CLRWINDOW   Clear a section of the screen 
  35.     FDUMPARRAY  Dump array contents to text file
  36.     GETPASS     Get a password from the user
  37.     GETSIZE     Get the size of an array
  38.     MEMSTAT     Return memory status (Lattice version only)
  39.     PEEK        Examine a memory location 
  40.     POKE        Place a value in a memory location
  41.     PUTWINDOW   Put a window around an area of the screen
  42.     RNARRAY     Rename an array
  43.     SETBELL     Set a flag to ring the bell on error
  44.     SOUND       Generate a sound of specific frequency
  45.                 & duration
  46.  
  47. Acknowledgement and our thanks are due Frank Fedele of Essential Software,
  48. Inc., who provided the following C routines:
  49.  
  50.     getpass, peekpoke, sound, curback, curfwd, getkey, segmov,
  51.     checkkey, savwindo, rstwindo, wnd2disk, wndfrdsk, memtoscr,
  52.     scrtomem, getkeycl, gdosint.
  53.  
  54. The above routines were excerpted from the C Utility Library, published
  55. by Essential Software. Source code is provide for some, but not all, 
  56. of the above functions. The entire library of over 300 C functions, 
  57. including complete source code, is available from:
  58.  
  59.                            Essential Software, Inc.
  60.                            P. O. Box 1003
  61.                            Maplewood, NJ  07040
  62.                            (914) 762-6605
  63.  
  64. 2. DOCUMENTATION NOTE: The <size> parameter for all of the statistics 
  65. functions is an optional parameter. The documentation did not 
  66. reflect this, but the help lines in this version have been updated.
  67.  
  68.  
  69. 3. New Error Messages: Two new error messages are possible with 
  70.    this version:
  71.  
  72.      11  Invalid calling syntax for this function
  73.          This error message appears if the syntax used for the 
  74.      command is incorrect. For example, the order of the
  75.      parameters may be incorrect, or required parameters 
  76.      may be missing.
  77.  
  78.      12  I/O Error
  79.          An I/O error has occurred during a disk operation, 
  80.      probably during an ARESTORE or ASAVE function. This could
  81.      be caused by several things. For example, a file might
  82.      be write protected or non-existent, there may be no more
  83.      room on the disk, etc.
  84.  
  85.  
  86. 4. Compiler Variations
  87.  
  88.   Beginning with Version 1.4 of dBASE Tools For C: The Programmer's 
  89.   Library, the following C Compilers are supported:
  90.  
  91.     Lattice Version 3.x
  92.     Microsoft Version 4.0
  93.     Aztec C Prime (Manx Systems)
  94.  
  95.   The following differences apply to versions of the product produced
  96.   with the above compilers:
  97.  
  98.   MEMSTAT works only with the Lattice versions
  99.  
  100.   STARRAY reports available memory only with Lattice versions.
  101.  
  102.   Remember that both Lattice versions and the Microsoft version
  103.   use the LARGE memory model, while Aztec C Prime is the small
  104.   model.
  105.  
  106.   Array limits in the AZTEC version are different from the other
  107.   compiler versions. See the README files for further details.
  108.  
  109.   The program size and array sizes are different for the
  110.   various versions. Therefore, the total amount of memory
  111.   consumed by each version is different. When the program is
  112.   run, the total number of pages being kept resident in
  113.   memory appears in parenthesis after the 'Installing ....'
  114.   message.
  115.  
  116.   The random number generators vary among the compilers. Note
  117.   in particular that the Microsoft rand() function generates
  118.   integers, while the other compilers can generate fractions
  119.   between 0 and 1. The degree of 'randomness' varies as well,
  120.   with the Lattice versions appearing to have the most
  121.   sophisticated algorithms.
  122.  
  123.   It is recommended that you examine the conditional 
  124.   compilation statements (#ifdef and #ifndef) in the source
  125.   code to gain a bettter understanding of the differences
  126.   among the different compiler versions.
  127.  
  128.   WARNING TO USERS OF AZTEC AND MICROSOFT VERSIONS: 
  129.   The amount of space to be allocated to arrays (as specified by
  130.   default or on the command line) MUST NOT be exceeded by any
  131.   function call. Since the program is resident, and has a fixed
  132.   amount of space available to it, any requests for memory beyond
  133.   that space will interfere with dBASE's use of the memory pool,
  134.   and the system will almost certainly lock up or behave in
  135.   an unpredictable manner. Typically, the system will behave as
  136.   if your request for more space was accepted, and then give
  137.   errors, or not work at all, with subsequent function calls.
  138.  
  139.   Pay particular attention when using character arrays: It is 
  140.   possible to create an empty array of legitimate size and then 
  141.   overstep the bounds of protected memory when placing values into 
  142.   it. This can occur because the array is initially sized only with 
  143.   index pointers for character arrays, but the ultimate size of 
  144.   the array also includes the size of each character element.
  145.  
  146.   The Lattice versions use the sizmem() function to determine 
  147.   if requests for allocation would exceed the available memory
  148.   pool, and thus are able to accurately report the amount of memory
  149.   actually available to the program, which is always checked
  150.   against memory requests. An equivalent function is not
  151.   provided by the Microsoft or Aztec libraries. Functions which
  152.   are particularly prone to this problem are ARESTORE, CRARRAY,
  153.   and PUTARRAY.
  154.  
  155.  
  156. 5. Notes on Recompiling The Programmer's Library
  157.  
  158.   The files on this disk are a complete replacement for the files
  159.   delivered with your previous version of dBASE Tools for C,
  160.   with the exception of CFUNC.BIN, which is not contained on this 
  161.   disk, and any .PRG files (such as DCT1.prg) you may want to keep.
  162.  
  163.   From the \SOURCE Directory:
  164.  
  165.    DCTMAIN.H    The main header file for your programs
  166.    INTREGS.H    Header file used with PEEKPOKE.C 
  167.    DCT1.C       Contains the "main" and all functions
  168.    DBARRAY.C    The array package
  169.    DBFIN.C      The financial functions
  170.    DBSTAT.C     The statistics functions
  171.    DCTMSG.C     Message functions used to display errors, etc.
  172.    PUTWINDO.C   Low-level function used by PUTWINDOW
  173.    GETPASS.C    Low-level function used by GETPASS
  174.    PEEKPOKE.C   Low-level functions used by PEEK and POKE
  175.    SAVWINDO.C   These last two source files contain routines
  176.    RSTWINDO.C      used by DCTMSG to do windowing.
  177.  
  178.   Note that some of the above files are replacements for the previous
  179.   file of the same name (from the original package), while others are 
  180.   completely new.
  181.  
  182.   You will be able to create the object files and libraries that you
  183.   need from the source files listed above, with the exception of the 
  184.   two following library files found in the subdirectories on your disk:
  185.  
  186.    DCTMISC.LIB    "Miscellaneous" proprietary routines.
  187.    xx_CATCH.LIB   Compiler-specific 'interrupt catching' functions
  188.  
  189.   where xx_CATCH.LIB is one of the following:
  190.  
  191.    L2_CATCH.LIB   For Lattice version 2.15
  192.    L3_CATCH.LIB   For Lattice version 3.0
  193.    MS_CATCH.LIB   For Microsoft version 3.0
  194.    AZ_CATCH.LIB   For Aztec C PRIME from Manx Software
  195.  
  196.   Both DCTMISC.LIB and xx_CATCH.LIB are compiler-specific; i.e., 
  197.   you will need to copy the version of the libraries located in 
  198.   the directory for your particular compiler. 
  199.  
  200.  
  201. 6. Pre-Parsing of CFUNC Parameters
  202.  
  203.   In addition to the GetFunc, GetNext, and GetString macros, this
  204.   version provides the arrays ArgVal[0]...ArgVal[MAXARGS], which
  205.   are characters arrays that are filled with the parameters of
  206.   each function call. For example, the RAND function call:
  207.             CALL cfunc WITH 'RAND 1,100'
  208.   causes the following values to be placed in the ArgVal arrays:
  209.             ArgVal[0] = 'RAND'
  210.             ArgVal[1] = '1'
  211.             ArgVal[2] = '100'
  212.   This pre-parsing makes it much simpler to write setup functions,
  213.   and also results in a significant savings in code size, since
  214.   each setup function no longer has to parse its own values. Almost
  215.   all of the setup functions in DCT1.C use this convention, except
  216.   for functions that need to parse a multiple-word string (such
  217.   as PUTARRAY when used with character arrays). Note that the old
  218.   GetFunc, GetNext, and GetString macros can still be used as
  219.   before, if desired.
  220.  
  221. 7. Documentation Pages for New Functions
  222.  
  223.   The new functions are fully documented in the following pages:
  224.  
  225.  
  226. NAME
  227.      ARAND - Fill an array with random #'s
  228.     
  229. SYNTAX
  230.      CALL cfunc WITH 'ARAND <array>[, <factor>,<start>,<end>]'
  231.     
  232. PARAMETERS
  233.      <array>    Name of array to fill
  234.      <factor>   Mutliply each random fraction by this #
  235.      <start>    Begin filling at this offset
  236.      <end>      End filling at this offset
  237.  
  238. DESCRIPTION
  239.      Fills the <start> to <end> elements of the array <array> with the
  240.      result of a random fraction multplied by <factor>. If <factor>
  241.      is not given, the default factor of 1 is used. If <end> is not
  242.      given, the entire array is filled.
  243.  
  244. RETURNS
  245.      Nothing
  246.  
  247. EXAMPLES
  248.      * Create an array, and fill it with 100 random numbers 
  249.      * between 0 and 10
  250.  
  251.      CALL cfunc WITH 'CRARRAY randarray,100,n'
  252.      CALL cfunc WITH 'ARAND randarray,10'
  253.  
  254. NOTES
  255.     An explicit factor of 0 will, in fact, multiply each random # by
  256.     0. This is a convenient way of initializing a range of elements
  257.     in an array to zero. Note that this should not be seen as 
  258.     'clearing' an array since the count will not be set to 0. Note
  259.     also that implying a factor of 0 by omitting the <factor> 
  260.     parameter is not the same as an explicit 0, and will instead
  261.     default to a value of 1 as described above.
  262.  
  263.     <Start> and <end> values, if included, must be positive.
  264.  
  265.  
  266. NAME
  267.      ARESTORE   Restore the elements of an array from a disk file
  268.     
  269. SYNTAX
  270.      CALL cfunc WITH 'ARESTORE <array>, <filename>[, <start>, <end>]'
  271.     
  272. PARAMETERS
  273.     <array>     array name
  274.     <filename>  name of disk file (created with ASAVE)
  275.     <start>     offset at which to start restoring to
  276.     <end>       last offset to restore to
  277.  
  278. DESCRIPTION
  279.      ARESTORE restores the contents of <array> from the disk file
  280.      <filename>, which is assumed to be a file created by the
  281.      ASAVE function. If <start> is given, the elements will be restored
  282.      to <array> beginning with the offset <start>. If <end> is given,
  283.      the restoration will stop at the <end> element of <array> or with 
  284.      the last element actually present in the file, whichever comes first.
  285.      If <end> is not given, <end> is assumed to be the largest offset
  286.      in the array. Note that the offsets <start> and <end> are for
  287.      <array>, not for <filename>. That is, if the command
  288.  
  289.             CALL CFUNC WITH 'ARESTORE SAVEIT SAVEIT.ARR 5 10'
  290.  
  291.      is given, the first element in SAVEIT.ARR will be read into offset
  292.      5 of the SAVIT array (which will correspond to the 6th position), and
  293.      subsequent values stored in the file will be read into consecutive
  294.      positions, until the sixth value in the file is restored to offset
  295.      10 (11th position) in the array. If <start> and <end> are both 
  296.      omitted, all the elements previously stored in the file will be
  297.      inserted in the array. The file <filename> remains unmodified.
  298.  
  299.      <Start> and <end> values, if included, must be positive.
  300. RETURNS
  301.     Returns <start> + the number of elements restored.
  302.         Return variable is c_n_result.
  303.  
  304. EXAMPLES
  305.     Restore the array members saved in the ASAVE example:
  306.  
  307.     . CALL cfunc WITH 'ARESTORE USERSTUF,USERSTUF.SAV'
  308.  
  309.  
  310. NAME
  311.      ASAVE   Save the elements of an array to a disk file
  312.     
  313. SYNTAX
  314.      CALL cfunc WITH 'ASAVE <array>, <filename>[, <start>, <end>]'
  315.     
  316. PARAMETERS
  317.     <array>     array name
  318.     <filename>  name of disk file to create
  319.     <start>     offset from which to start saving
  320.     <end>       last element to save
  321.  
  322. DESCRIPTION
  323.      ASAVE stores the contents of <array> to disk. <filename> can
  324.      be any legal DOS file name, including disk and path
  325.      designators (for example: "A:\ARRAYS\TEMP\MYSTUFF.SAV"). If
  326.      the file <filename> already exists on the disk, its original
  327.      contents will be lost and replaced with the new values in
  328.      <array>. If <start> is given, the contents will be saved
  329.      beginning with the offset specified by <start>, and ending
  330.      with the offset specified by the optional <end>, if present,
  331.      or until all elements of the array are written to the file,
  332.      if <end> is not present. If <start> and <end> are not given,
  333.      all the elements of the array are saved.
  334.  
  335. RETURNS
  336.      Returns the actual number of elements stored.
  337.      Return variable is c_n_result.
  338.  
  339. EXAMPLES
  340.     Save the first 10 elements of the array USERSTUF to disk:
  341.  
  342.     . CALL cfunc WITH 'ASAVE USERSTUF,USERSTUF.SAV,10'
  343.  
  344. NOTES
  345.     ASAVE stores numbers to six decimal places.
  346.     <Start> and <end>, if included, must be positive.
  347.  
  348.  
  349. NAME
  350.      CHI  Calculate chi-square statistic
  351.     
  352. SYNTAX
  353.      CALL cfunc WITH 'CHI <expected>, <observed>[,<n>]
  354.     
  355. PARAMETERS
  356.     <expected>  Array of expected values
  357.     <observed>  Array of observed values
  358.     <n>         Size of arrays
  359.  
  360. DESCRIPTION
  361.        Calculates the chi-square statistic, according to
  362.        the following formula:
  363.  
  364.        V = (expected[0]-observed[0])^2 / expected[0]
  365.          + (expected[1]-observed[1])^2 / expected[1]
  366.          
  367.             .
  368.             .
  369.             .
  370.          
  371.          + (expected[n-1]-observed[n-1])^2 / expected[n-1]
  372.  
  373. RETURNS
  374.         Returns the chi-square statistic to the dBASE
  375.         numeric variable.
  376.         
  377.         Return variable is c_n_result.
  378.  
  379. EXAMPLES
  380. * The following example uses Don Knuth's results of dice-throwing
  381. * in volume 2 of "The Art of Computer Programming: Seminumerical
  382. * Algortithms," pages 39-42.
  383.  
  384.         call cfunc with 'crarray expected,11,n'
  385.         call cfunc with 'crarray observed,11,n'
  386.         call cfunc with 'putarray expected,  0, 4'
  387.         call cfunc with 'putarray expected,  1, 8'
  388.         call cfunc with 'putarray expected,  2, 12'
  389.         call cfunc with 'putarray expected,  3, 16'
  390.         call cfunc with 'putarray expected,  4, 20'
  391.         call cfunc with 'putarray expected,  5, 24'
  392.         call cfunc with 'putarray expected,  6, 20'
  393.         call cfunc with 'putarray expected,  7, 16'
  394.         call cfunc with 'putarray expected,  8, 12'
  395.         call cfunc with 'putarray expected,  9, 8'
  396.         call cfunc with 'putarray expected,  10, 4'
  397.  
  398.         call cfunc with 'putarray observed,  0, 2'
  399.         call cfunc with 'putarray observed,  1, 4'
  400.         call cfunc with 'putarray observed,  2, 10'
  401.         call cfunc with 'putarray observed,  3, 12'
  402.         call cfunc with 'putarray observed,  4, 22'
  403.         call cfunc with 'putarray observed,  5, 29'
  404.         call cfunc with 'putarray observed,  6, 21'
  405.         call cfunc with 'putarray observed,  7, 15'
  406.         call cfunc with 'putarray observed,  8, 14'
  407.         call cfunc with 'putarray observed,  9, 9'
  408.         call cfunc with 'putarray observed,  10, 6'
  409.  
  410.         call cfunc with 'chi expected, observed, 11'
  411.         ? 'chi-square = ', c_n_result
  412.  
  413.  
  414. NAME
  415.      CLRWINDOW     Clear a section of the screen
  416.     
  417. SYNTAX
  418.      CALL cfunc WITH 'CLRWINDOW <y1>,<x1>,<y2>,<x2>[,<flag>]'
  419.     
  420. PARAMETERS
  421.      <x1>,<y1>  Coordinates of upper left corner of window
  422.      <x2>,<y2>  Coordinates of lower right corner of window
  423.      <flag>     Optional flag to clear interior
  424.  
  425. DESCRIPTION
  426.      Clears the area defined by the given coordinates to spaces. If
  427.      <flag> is non-zero, only the borders of the window
  428.      are cleared. If <flag> is zero or omitted, clears the 
  429.      border and its contents. <x1> and <x2> refer to column numbers,
  430.      and <y1> and <y2> refer to row numbers.
  431.  
  432. RETURNS
  433.      Nothing
  434.  
  435. EXAMPLES
  436.      * Clear the first 4 lines of the screen:
  437.      call cfunc with 'clrwindow 0,0,3,79'
  438.  
  439. NOTES
  440.      See PUTWINDOW.
  441.  
  442.  
  443. NAME
  444.      FDUMPARRAY     Dump array contents to text file
  445.     
  446. SYNTAX
  447.      CALL cfunc WITH 'FDUMPARRAY <array>,<fname>,<start>,<end>'
  448.     
  449. PARAMETERS
  450.      <array>    Array name
  451.      <fname>    File Name
  452.      <start>    Begin at this offset
  453.      <end>      End at this offset
  454.  
  455. DESCRIPTION
  456.      Dumps the contents of <array> to the text file <fname>, beginning
  457.      at offset <start> and ending at offset <end>. If <fname> already
  458.      exists, it is overwritten.  FDUMPARRAY includes the index numbers 
  459.      of the array elements.
  460.  
  461. RETURNS
  462.      Returns the actual count of elements in the array to the
  463.      c_n_result variable.
  464.  
  465. NOTE
  466.      <Start> and <end> values must be positive.
  467.  
  468.  
  469. NAME
  470.      GETPASS    Get a password from the user
  471.     
  472. SYNTAX
  473.      CALL cfunc WITH 'GETPASS'
  474.     
  475. PARAMETERS
  476.     None
  477.  
  478. DESCRIPTION
  479.     Gets an 8-character password from the user. The character '#'
  480.     is echoed for each character entered from the keyboard. Only 
  481.     alphanumeric characters can be entered, and invalid characters
  482.     will produce a beep. The backspace key can be used to delete
  483.     characters.
  484.  
  485. RETURNS
  486.     Returns the password to the c_c_result variable.
  487.  
  488.  
  489.  
  490.  
  491. NAME
  492.      GETSIZE    Get the size of an array
  493.     
  494. SYNTAX
  495.      CALL cfunc WITH 'GETSIZE <array>'
  496.     
  497. PARAMETERS
  498.     <array>  Name of an array created eariler with CRARRAY
  499.  
  500. DESCRIPTION
  501.     Gets the size that <array> was created with.
  502.  
  503. RETURNS
  504.     Returns the size to the c_n_result variable.
  505.  
  506.  
  507.  
  508.  
  509. NAME
  510.      MEMSTAT    Get the status of available memory
  511.     
  512. SYNTAX
  513.      CALL cfunc WITH 'MEMSTAT'
  514.     
  515. PARAMETERS
  516.      NONE
  517.  
  518. DESCRIPTION
  519.      Calculates the amount of memory available for arrays.
  520.  
  521. RETURNS
  522.      Returns the available memory to the c_n_result variable
  523.  
  524. NOTE
  525.      Valid only for the LATTICE version.
  526.  
  527.  
  528. NAME
  529.      PEEK - Examine the contents of a memory location
  530.     
  531. SYNTAX
  532.      CALL cfunc WITH 'PEEK <offset>, <segment>'
  533.     
  534. PARAMETERS
  535.     <offset>    Decimal address of memory offset
  536.     <segment>   Decimal address of memory segment
  537.  
  538. DESCRIPTION
  539.     Returns the byte located at the indicated segment and
  540.     offset.
  541.  
  542. RETURNS
  543.     Returns the contents of the memory location to c_n_result.
  544.  
  545.  
  546.  
  547.  
  548.  
  549. NAME
  550.      POKE - Place a value in a memory location
  551.     
  552. SYNTAX
  553.      CALL cfunc WITH 'POKE <bytecode>, <offset>, <segment>' 
  554.     
  555. PARAMETERS
  556.      <bytecode> Decimal value to place in memory
  557.      <offset>   Decimal address of memory offset
  558.      <segment>  Decimal address of memory segment
  559.  
  560. DESCRIPTION
  561.      Writes the value of <bytecode> to the memory location
  562.      specified by <offset> and <segment>.  Valid numbers for
  563.      <bytecode> are -128 through +127.
  564.  
  565. RETURNS
  566.      Nothing
  567.  
  568.  
  569.  
  570.  
  571.  
  572. NAME
  573.      PUTWINDOW   Draw a window on the screen
  574.     
  575. SYNTAX
  576.      CALL cfunc WITH 'PUTWINDOW <y1>,<x1>,<y2>,<x2>,<clear>,<type>'
  577.     
  578. PARAMETERS
  579.      <y1>,<x1>  Coordinates of upper left corner of window
  580.      <y2>,<x2>  Coordinates of lower right corner of window
  581.      <clear>    Non-zero if window should be filled with spaces
  582.      <type> 0 for single-line window, non-zero for double-line
  583.  
  584. DESCRIPTION
  585.      Draws a window over the specified coordinates.
  586.  
  587. RETURNS
  588.      Nothing
  589.  
  590. NOTES
  591.      If coordinates outside the screen boundary are passed, or if the
  592.      numbers passed for the first corner are larger than the numbers
  593.      passed for the second corner, unexpected results may be seen.
  594.  
  595.      See CLRWINDOW.
  596.  
  597.  
  598.  
  599. NAME
  600.      RNARRAY    Rename an array
  601.     
  602. SYNTAX
  603.      CALL cfunc WITH 'RNARRAY <oldname>, <newname>'
  604.     
  605. PARAMETERS
  606.     <oldname>   Current name of array
  607.     <newname>   New name to use for array
  608.  
  609.  
  610. DESCRIPTION
  611.     Renames the array <oldname> to <newname>. This is
  612.     equivalent to saving the contents of <oldname>, freeing
  613.     the array <oldname>, creating a new array called <newname>
  614.     that is the same size as <oldname>, and restoring the
  615.     contents to <newname>.
  616.  
  617. RETURNS
  618.     Nothing.
  619.  
  620.  
  621. NAME
  622.      SETBELL    Set error bell on/off
  623.     
  624. SYNTAX
  625.      CALL cfunc WITH 'SETBELL <value>'
  626.     
  627. PARAMETERS
  628.     <value>     0 (OFF) or non-zero (ON)
  629.  
  630.  
  631. DESCRIPTION
  632.     Normally, errors produce a bell sound and an error message. SETBELL
  633.     can be used to turn this bell off (or back on). If <value> is 0 or
  634.     any expression that evaluates to zero (such as any non-numeric 
  635.     string), the bell is turned off. If <value> is a non-zero number, it
  636.     is turned on. The flag is set to ON upon start-up.
  637.  
  638. RETURNS
  639.     Nothing.
  640.  
  641.  
  642. NAME
  643.      SOUND   Generate a sound on the speaker
  644.     
  645. SYNTAX
  646.      CALL cfunc WITH 'SOUND <frequency>, <duration>'
  647.     
  648. PARAMETERS
  649.     <frequency> Frequency of sound in MHz
  650.     <duration>  Duration in clock ticks
  651.  
  652. DESCRIPTION
  653.     Generates a sound of the specified frequency and 
  654.     duration. <duration> is in clock ticks, and must be
  655.     between 0 and 65535. There are approxiately 18.2 
  656.     clock ticks per second.
  657.  
  658. RETURNS
  659.     Nothing
  660.  
  661. EXAMPLES
  662. * Produce a glissando (sliding scale)
  663.  
  664. i = 440
  665. do while i <= 1000
  666.     call cfunc with 'sound '+str(i)+',1'
  667.     i = i+5
  668. enddo
  669. do while i >= 440
  670.     call cfunc with 'sound '+str(i)+',1'
  671.     i = i-5
  672. enddo
  673.  
  674.  
  675.  
  676.